home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
TeX 1995 July
/
TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO
/
web
/
fweb
/
fweb-1.40
/
manual
/
fweb.info-2
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-10-29
|
51KB
|
1,044 lines
This is Info file fweb.info, produced by Makeinfo-1.55 from the input
file fweb.texinfo.
This file documents FWEB...
Copyright 1993 John A. Krommes
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission
notice are preserved on all copies.
Permission is granted to process this file through TeX and
print the results, provided the printed document carries a copying
permission notice identical to this one except for the removal of
this paragraph (this paragraph not being relevant to the printed
manual).
Permission is granted to copy and distribute modified versions
of this manual under the conditions for verbatim copying, provided
also that the section entitled "Copying" is included exactly as in
the original, and provided that the entire resulting derived work
is distributed under the terms of a permission notice identical to
this one.
Permission is granted to copy and distribute translations of
this manual into another language, under the above conditions for
modified versions, except that this permission notice may be
stated in a translation approved by the author.
File: fweb.info, Node: -F_, Next: -f, Prev: -e, Up: Options
`-F': Compare output files with old versions.
----------------------------------------------
When the `-F' option is in effect, FTANGLE writes its output to a
temporary file (or files) instead of to its ultimate destination--e.g.,
`test.c' and/or `test.f'. After all output is written, the temporary
files are compared with the old version of the files, if they exist.
If the files are identical, the appropriate temporary file is deleted;
otherwise, the temporary file is renamed, effectively overwriting the
old version. This feature avoids updating the time stamp on the file
unnecessarily, so `make' files won't recompile the output unless it
really has to.
(Note that with this option in effect, if one used the Unix utility
`touch' to force processing of a group of files, but the WEB sources
are never changed, the `make' file will continue to tangle the sources
no matter how many times it is run, since FTANGLE will never update the
time stamp on the files.)
The location of the temporary file as well as details of the renaming
procedure are determined by the automatic configuration script during
installation of the processors. The script `./configure' first looks
for the (non-ANSI) function `tempnam'. If it finds it, it uses it to
place the temporary file in the directory that FWEB would normally use
for output in the absence of the `-F' option. (That is usually the
current directory.) If `tempnam' is not available, the ANSI routine
`tmpnam' is used. That places the temporary file in a directory
determined by the system.
To implement the renaming, the `rename' function is used. This may
fail if `tmpnam' placed the temporary file on a different device. If
so, an attempt is made to force the rename by using the |system|
routine to issue a `mv' command. Terminal output indicates the
progress of the renaming. An asterisk following an output file name
indicates that `rename' did not succeed, but the `mv' command did.
File: fweb.info, Node: -f, Next: -h, Prev: -F_, Up: Options
`-f': Turn off module references for identifiers.
--------------------------------------------------
By default, FWEAVE gives certain entities such as function names a
section-number subscript to indicate where that function was defined.
The `-f' command turns off the subscripting operation.
The subscript operations are further controlled by the settings of
the style-file parameters `mark_defined'. *Note S_mark_defined::.
File: fweb.info, Node: -h, Next: -I_, Prev: -f, Up: Options
`-h': Get help.
----------------
This just prints a message saying where further help is available.
File: fweb.info, Node: -I_, Next: -i, Prev: -h, Up: Options
`-I': Append to search list for include files.
-----------------------------------------------
The fundamental search list for include files is defined by the
environment variable `FWEB_INCLUDES', which is a colon-delimited list
such as
setenv FWEB_INCLUDES .:/usr/fweb:/other/stuff
The `-I' option appends to this list.
File: fweb.info, Node: -i, Next: -i!, Prev: -I_, Up: Options
`-i': Don't print `@I' include files.
--------------------------------------
If a web file is included via `@I' (*note ATI_::.), for example
@I formats.hweb
then the `-i' option means to read and process the web file, but don't
print its contents. This option is often used for large files of macro
definitions, formats, or typedef statements that must be included at the
beginning of even very short web files; it clutters things up to print
such header files all the time.
Note that files included via `@i' do not respond to `-i' or `-i!'.
File: fweb.info, Node: -i!, Next: -L_, Prev: -i, Up: Options
`-i!': Don't read `@I' include files.
--------------------------------------
If a web file is included via `@I', for example
@I formats.hweb
then the `-i!' option means to ignore such files completely. This
option is seldom useful; the `-i' option (*note -i::.) is more often
used.
File: fweb.info, Node: -L_, Next: -l, Prev: -i!, Up: Options
`-L': Select global language.
------------------------------
To select a global language from the command line, say `-Ll', where
l is one of `{c,c++,n,n9,r,r9,x}'. *Note Languages::.
File: fweb.info, Node: -l, Next: -m, Prev: -L_, Up: Options
`-l': Echo input line.
-----------------------
The option `-l[mmm[:nnn]]' echoes the input line constructed by the
input driver between lines mmm and nnn. Missing nnn means echo to the
end of file. Missing mmm means echo from the beginning.
This option is useful as a debugging tool. It is often used to
verify that the input driver is inserting semicolons correctly. For
Fortran-77, it is also useful to verify that comments are being
processed correctly.
File: fweb.info, Node: -m, Next: -m4, Prev: -l, Up: Options
`-m': Define WEB macro.
------------------------
The command-line construction
-mA(x)=x
defines the WEB macro `A' as though the definition
@m A(x) x
had appeared at the beginning of the web file.
File: fweb.info, Node: -m4, Next: -m;, Prev: -m, Up: Options
`-m4': Understand `m4' built-in commands.
------------------------------------------
This tells FWEAVE to properly format the reserved words of the `m4'
preprocessor. The use of this preprocessor is *not recommended*; use
FWEB's built-in preprocessor instead.
File: fweb.info, Node: -m;, Next: -n, Prev: -m4, Up: Options
`-m;': Append pseudo-semicolons.
---------------------------------
When `-m;' is in effect, the construction `@;' is appended
automatically to all WEB macro definitions.
*This option is not recommended.* Insert the `@;' by hand when
necessary, as in
@m SET(x,y) x=1; y=2@;
File: fweb.info, Node: -n, Next: -n9, Prev: -m;, Up: Options
`-n': Set global language to Fortran-77.
-----------------------------------------
*Note Languages::, *Note Fortran::.
File: fweb.info, Node: -n9, Next: -n;, Prev: -n, Up: Options
`-n9': Set global language to Fortran-90.
------------------------------------------
*Note Languages::, *Note Fortran::.
File: fweb.info, Node: -n;, Next: -nb, Prev: -n9, Up: Options
`-n;': Supply automatic semicolons (Fortran).
----------------------------------------------
This is the default mode of operation in Fortran-77; the input driver
automatically appends a semicolon to each logical line of source code.
Since it's the default, you don't have to use it unless you wish to
negate it. *Note Negating options::.
File: fweb.info, Node: -nb, Next: -np, Prev: -n;, Up: Options
`-nb': Number `if's and `do's (Fortran).
-----------------------------------------
In the woven output, extra comments are added to help one correlate
the block structure of the code.
File: fweb.info, Node: -np, Next: -n\, Prev: -nb, Up: Options
`-np': Print semicolons (Fortran).
-----------------------------------
Although the Fortran input driver automatically terminates logical
lines with semicolons so that the innards of FWEAVE can process them
correctly, the semicolons are by default not printed. To make them be
printed, use the `-np' option.
File: fweb.info, Node: -n\, Next: -n&, Prev: -np, Up: Options
`-n\': Free-form syntax continued by backslash.
------------------------------------------------
In Fortran-90, this turns on free-form syntax and sets the
continuation character to be the backslash. For example,
-n9[-n\]
@
@a
program main;
x = \
y;
end;
In the tangled output the backslash is converted into Fortran-90's
standard continuation character, the ampersand.
File: fweb.info, Node: -n&, Next: -n/, Prev: -n\, Up: Options
`-n&': Free-form syntax continued by ampersand.
------------------------------------------------
In Fortran-90, this turns on free-form syntax and sets the
continuation character to be the backslash. For example,
-n9[-n\]
@
@a
program main;
x = &
y;
end;
File: fweb.info, Node: -n/, Next: -n!, Prev: -n&, Up: Options
`-n/': Recognize short comments (Fortran).
-------------------------------------------
The standard FWEB notation for a short comment is `// ...'. However,
in Fortran the `//' denotes concatenation by default. To make it denote
a short comment, use the `-n/' option. For concatenation, use `\/'.
File: fweb.info, Node: -n!, Next: -n), Prev: -n/, Up: Options
`-n!': Make `!' denote short comment (Fortran).
------------------------------------------------
File: fweb.info, Node: -n), Next: -o, Prev: -n!, Up: Options
`-n)': Reverse array indices (Fortran)
---------------------------------------
This flag permits Fortran programmers to use C-style array indices.
Conversions such as the following are made:
a(k)(i) => a(i,k)
a(k)(i,j) => a(i,j,k)
a(k)(j)(i) => a(i,j,k)
This feature permits convenient definitions of macros to deal with
multi-dimensional vectors.
File: fweb.info, Node: -o, Next: -q, Prev: -n), Up: Options
`-o': Don't overload operators.
--------------------------------
(To be finished.)
File: fweb.info, Node: -q, Next: -P_, Prev: -o, Up: Options
`-q': Don't translate Ratfor.
------------------------------
*(Obsolete.)*
File: fweb.info, Node: -P_, Next: -p, Prev: -q, Up: Options
`-P': Select TeX processor.
----------------------------
Say `-PT' or `-PL' to inform FWEAVE that its output will be
processed by TeX or LaTeX, respectively. If you always use LaTeX, it's
easiest to put `+PL' into the `.fweb' initialization file.
File: fweb.info, Node: -p, Next: -r, Prev: -P_, Up: Options
`-p': Buffer up a style-file entry.
------------------------------------
This option can be used in the `.fweb' initialization file to record
style-file entries that are common to all runs. This command buffers
up the entries. They are effectively placed at the beginning of the
local style file, which is read after the command line is processed.
*Note Style::.
File: fweb.info, Node: -r, Next: -r9, Prev: -p, Up: Options
`-r': Set global language to Ratfor-77.
----------------------------------------
*Note Languages::, *Note Ratfor::.
File: fweb.info, Node: -r9, Next: -rg, Prev: -r, Up: Options
`-r9': Set global language to Ratfor-90.
-----------------------------------------
*Note Languages::, *Note Ratfor::.
File: fweb.info, Node: -rg, Next: -rk, Prev: -r9, Up: Options
`-rg': Set `goto' parameters.
------------------------------
This obscure parameter is used for Ratfor (and really should be a
style-file parameter). Please see the manual.
File: fweb.info, Node: -rk, Next: -rK_, Prev: -rg, Up: Options
`-k': Suppress comments about Ratfor translation.
---------------------------------------------------
By default, the Ratfor translator writes comments about what command
it is translating. The `-k' option suppresses those comments.
Arguments to this command allows one to suppress comments about only
particular commands; please see the reference guide.
File: fweb.info, Node: -rK_, Next: -r;, Prev: -rk, Up: Options
`-K': Write comments about Ratfor translation.
------------------------------------------------
This is the negative of `-k'; it forces comments about particular
Ratfor commands.
File: fweb.info, Node: -r;, Next: -rb, Prev: -rK_, Up: Options
`-r;': Turn on auto-semi mode (Ratfor).
----------------------------------------
Please don't use this command. Insert semicolons by hand in your
Ratfor code.
File: fweb.info, Node: -rb, Next: -r/, Prev: -r;, Up: Options
`-rb': Number `if's and `do's (Ratfor).
----------------------------------------
In the woven output, extra comments are added to help one correlate
the block structure of the code.
File: fweb.info, Node: -r/, Next: -r!, Prev: -rb, Up: Options
`-r/': Recognize short comments (Ratfor).
------------------------------------------
The standard FWEB notation for a short comment is `// ...'. However,
in Ratfor the `//' denotes concatenation by default. To make it denote
a short comment, use the `-r/' option. For concatenation, use `\/'.
File: fweb.info, Node: -r!, Next: -r), Prev: -r/, Up: Options
`-r!': Make `!' denote short comment (Ratfor).
-----------------------------------------------
File: fweb.info, Node: -r), Next: -s, Prev: -r!, Up: Options
`-r)': Reverse array indices (Ratfor)
--------------------------------------
File: fweb.info, Node: -s, Next: -T_, Prev: -r), Up: Options
`-s': Print statistics.
------------------------
`-s' prints statistics about memory usage at the end of the run.
`-sm' prints statistics about memory usage at the end of the run,
just as does `-s'; it also prints information about dynamic memory
allocations as they occur. `-smnnn' displays allocations of nnn bytes
or more; if nnn is missing, 10000 is assumed.
File: fweb.info, Node: -T_, Next: -t, Prev: -s, Up: Options
`-T': Flag-setting commands for FTANGLE.
-----------------------------------------
This is a family of commands that set flags appropriate only for
FTANGLE.
* Menu:
* -TD:: Permit processing of deferred macro definitions.
* -Tv:: Don't print header info at top of output.
* -T%:: Don't retain trailing comments.
File: fweb.info, Node: -TD, Next: -Tv, Prev: -T_, Up: -T_
`-TD': Permit processing of deferred macro definitions
.......................................................
Deferred macro definitions are `@m' (or, equivalently, `@#define')
commands that appear in the code part rather than the usual definition
part. These definitions are evaluated during the output (phase 2), and
can cause confusion when used with the preprocessor commands, which are
evaluated during the input (phase 1). Because of this confusion,
deferred macro definitions are prohibited by default. To permit them,
use the `-TD' option.
File: fweb.info, Node: -Tv, Next: -T%, Prev: -TD, Up: -T_
`-Tv': Don't print header info
..............................
By default, FTANGLE attempts to be helpful and prints some
information about the command line, input and change files, etc. at the
beginning of the output file. This information can be deleted by means
of the `-Tv' flag. (This is done automatically when the `-F' flag is
in effect, since the header information includes a time stamp that would
defeat a successful file comparison.)
File: fweb.info, Node: -T%, Prev: -Tv, Up: -T_
`-T%': Don't retain trailing comments
......................................
Unless the `-v' option is used, comments are generally deleted by
FTANGLE as it writes the output file. However, in the TeX language
such deletions can change the behavior of the output (by introducing
extra spaces). Therefore, for TeX comments that do not begin a line
are always retained unless the `-T%' command is used. This command has
no effect for languages other than TeX.
File: fweb.info, Node: -t, Next: -U_, Prev: -T_, Up: Options
`-t': Truncate identifiers.
----------------------------
The truncation option enables one to use a wider character set for
identifiers than the language compiler will accept. The standard
example is vanilla-flavored Fortran, which doesn't allow the underscore.
If one says ``-tn6{_}'', underscores will be removed from all
identifiers, then the result will be truncated to length 6. If the
truncation procedure results in non-unique identifiers, these are
listed.
File: fweb.info, Node: -U_, Next: -u, Prev: -t, Up: Options
`-U': Convert reserved output tokens to lower case.
----------------------------------------------------
Particularly during RATFOR expansion, certain output tokens such as
`DO' are produced in upper case. The `-U' option forces such tokens to
be produced in lower case.
File: fweb.info, Node: -u, Next: -v, Prev: -U_, Up: Options
`-u': Undefine macro.
----------------------
`-uA' undefines the WEB macro previously defined on the command line
(or in `.fweb') via `-m'.
*CAUTION*: This command can also undefine built-in functions such
as `$IF'. Don't do that, since built-ins can use other built-ins
behind the scenes; undefining one can cause very strange behavior.
File: fweb.info, Node: -v, Next: -W_, Prev: -u, Up: Options
`-v': Make all comments verbatim.
----------------------------------
By default, comments are not passed to the tangled output. With
`-v', all comments are included verbatim in the tangled output.
File: fweb.info, Node: -W_, Next: -w, Prev: -v, Up: Options
`-W': Flag-setting commands for FWEAVE.
----------------------------------------
This is a family of commands that set flags appropriate only for
FWEAVE. Commands such as `-W[' and `-Wf' can be combined as `-W[f'.
* Menu:
* -W[:: Turn on processing of bracketed array indices.
* -Wdflmvw:: Don't print various things in woven output.
File: fweb.info, Node: -W[, Next: -Wdflmvw, Prev: -W_, Up: -W_
`-W[': Process bracketed array indices
.......................................
File: fweb.info, Node: -Wdflmvw, Prev: -W[, Up: -W_
`-Wdflmvw': Don't print various things in woven output
.......................................................
The printing of selected definition-part commands can be suppressed
as follows:
-Wd --- outer definitions
-Wf --- format statements
-Wl --- limbo text definitions
-Wm --- WEB macro definitions
-Wv --- operator overloads
-Ww --- identifier overloads
When these commands are used, associated cross-referencing is suppressed
as well.
File: fweb.info, Node: -w, Next: -x, Prev: -W_, Up: Options
`-w': Change name of macro package
-----------------------------------
The command `-w' means "Don't print `\input fwebmac.sty' as the first
line of the `.tex' output file." The command `-wfname' means "Print
`\input fname' as the first line."
File: fweb.info, Node: -x, Next: -X_, Prev: -w, Up: Options
`-x': Reduce cross-reference information.
------------------------------------------
Cross-reference information (for FWEAVE) includes the table of
contents ('c'), the index ('i'), and the module list ('m'). The
command `-x' eliminates all of that information. The command
`-xletters' eliminates the piece of information corresponding to each
letter in the list. For example, `-xim' eliminates the index and the
module list.
File: fweb.info, Node: -X_, Next: -y, Prev: -x, Up: Options
`-X': Print selected cross-reference information.
--------------------------------------------------
This command is the opposite of `-x'. *Note -x::.
File: fweb.info, Node: -y, Next: -Z_, Prev: -X_, Up: Options
`-y': Allocate dynamic memory.
-------------------------------
This command changes the default size for a dynamically allocated
memory buffer. The buffers are indicated by a one- or two-character
abbreviation such as "op". The command `-yop200' allocates 200 units
for the "op" buffer.
To query the default allocations, just say `-y'.
For a more detailed discussion of memory allocation and a menu of the
various dynamic arrays, see *Note Memory allocation::.
File: fweb.info, Node: -Z_, Next: -z, Prev: -y, Up: Options
`-Z': Display default style-file parameters.
---------------------------------------------
The command `-Zabc' prints to the screen the default contents of the
style-file parameters beginning with "abc". Just `-Z' prints
everything.
File: fweb.info, Node: -z, Next: -., Prev: -Z_, Up: Options
`-z': Change name of style file.
---------------------------------
The command `-znew.sty' changes the default style-file name
`fweb.sty' to `new.sty'. The command `-z' means "Don't read any style
file."
Normally the style file is read from the same directory in which the
WEB file resides. To force `fweb.sty' to be read from the current
directory, say `-z.'.
File: fweb.info, Node: -., Next: -\, Prev: -z, Up: Options
`-.': Don't recognize dot constants.
-------------------------------------
If this command is used, the processors will not understand that
constructions such as `.LT.' are operators in Fortran or Ratfor. This
command is useful if one is trying to modernize the source code to deal
with symbols such as `<' instead of `.LT.'.
File: fweb.info, Node: -\, Next: -lp, Prev: -., Up: Options
`-\': Explicitly escape continued strings.
-------------------------------------------
(To be finished.)
File: fweb.info, Node: -lp, Next: -colon, Prev: -\, Up: Options
`-(': Continue parenthesized strings with backslashes.
-------------------------------------------------------
File: fweb.info, Node: -colon, Next: ->, Prev: -lp, Up: Options
`-:': Set starting automatic statement number.
-----------------------------------------------
Useful for Fortran and Ratfor. Symbolic statement labels that are
defined with the `#:0' macro command are incremented starting with the
default of 90000. To change this to 789, say `-:789'.
File: fweb.info, Node: ->, Next: -=, Prev: -colon, Up: Options
`->': Redirect output.
-----------------------
This changes the name of the output file. If no name is given,
output is redirected to the terminal.
File: fweb.info, Node: -=, Next: -#, Prev: ->, Up: Options
`-=': Redirect output.
-----------------------
Equivalent to `->'.
File: fweb.info, Node: -#, Next: -plus, Prev: -=, Up: Options
`-#': Turn off comments about line and module numbers.
-------------------------------------------------------
By default, tangled output includes comments about the line and
module numbers corresponding to the current piece of code. To
eliminate this clutter, say `-#'.
In some cases, bugs in tangled output, particularly Fortran, can be
eliminated by using `-#'. (But please report the bug anyway; *Note
Support::.)
File: fweb.info, Node: -plus, Next: -/, Prev: -#, Up: Options
`-+': Don't interpret compound assignment operators.
-----------------------------------------------------
Both Ratfor and Fortran attempt to translate the commands `++',
`+=', `--', `-=', `*=', and `/=' into code that behaves as its C
counterpart. To turn this feature off, use `-+'.
File: fweb.info, Node: -/, Next: -!, Prev: -plus, Up: Options
`-/': Recognize short comments (Fortran & Ratfor).
---------------------------------------------------
If this command is not used, the `//' construction will be
interpreted as concatenation.
One way of invoking this option is with the global language command,
such as `@n/'. Another is to put the command into the initialization
file `.fweb'.
File: fweb.info, Node: -!, Next: Info options, Prev: -/, Up: Options
`-!': Make `!' denote short comment (Fortran & Ratfor).
--------------------------------------------------------
File: fweb.info, Node: AT commands, Next: Comments, Prev: Starting, Up: Top
WEB COMMANDS
************
All WEB commands begin with the character `@'. It is recommended
that these begin in column 1 if possible. This is required in some
cases [e.g., the `@x', `@y', and `@z' in change files (*note Change
files::.), or column-oriented Fortran processing].
Some of these control codes may be used anywhere; others begin a new
part. For a quick summary of the control-code mappings and to see which
codes begin new parts, use the `-@' option. *Note -AT::.
* Menu:
Debugging commands:
* @0: AT0. Turn off debugging.
* @1: AT1. Display irreducible scraps.
* @2: AT2. Display detailed scrap reductions.
Literal control characters:
* @@: ATAT. Insert an '@'.
* @|: AT|. Vertical bar/optional line break.
Beginning of section:
* @ : ATspace. Begin minor section.
* @*: AT*. Begin major section.
Beginning of code part:
* @<: AT<. Begin module name.
* @>: AT>. End module name.
* @A: ATA_. Begin code part.
* @a: ATa. Begin code part and mark next identifier.
Control codes b-z:
* @b: ATb. Insert breakpoint command.
* @c: ATc. Set language to C.
* @c++: ATcpp. Set language to C++.
* @D: ATD_. Define outer macro.
* @d: ATd. Define outer macro and mark it.
* @f: ATf. Format identifier or module name.
* @I: ATI_. Include a WEB file, but don't print it.
* @i: ATi. Include a WEB file.
* @L: ATL_. Set language.
* @l: ATl. Specify limbo text.
* @M: ATM_. Define a WEB macro.
* @m: ATm. Define a WEB macro and mark it.
* @N: ATN_. Turn on language-independent mode.
* @n: ATn. Set language to Fortran-77.
* @n9:ATn9. Set language to Fortran-90.
* @O: ATO_. Open new output file (global scope).
* @o: ATo. Open new output file (local scope).
* @r: ATr. Set language to Ratfor-77.
* @r9: ATr9. Set language to Ratfor-90.
* @u: ATu. Undefine an outer macro.
* @v: ATv. Overload an operator.
* @W: ATW_. Overload an identifier.
* @x: ATx. Terminate ignorable material.
* @y: ATy. End first part of change.
* @z: ATz. Begin ignorable material.
Conversion to ASCII:
* @': ATquote. Convert single character to ASCII.
* @": AT". Convert string to ASCII.
Forward referencing:
* @[: AT[. Mark next identifier as defined in this section.
Comments:
* @/*: AT/*. Begin a long verbatim comment.
* @//: AT//. Begin a short verbatim comment.
* @%: AT%. Ignore everything to next newline.
* @?: AT?. Begin a compiler directive.
* @(: ATlp. Begin a meta-comment.
* @): AT). End a meta-comment.
Special brace:
* @{: ATlb. Suppress default insertion of breakpoint command.
Index entries:
* @_: AT_. Force an index entry to be underlined (marked as defined).
* @-: AT-. Delete index entry for following identifier.
* @+: ATplus. Force index entry for following identifier.
* @^: AT^. Make index entry in Roman type.
* @.: ATdot. Make index entry in typewriter type.
* @9: AT9. Make index entry in format controlled by `\9'.
Control text:
* @t: ATt. Put control text into TeX \hbox.
* @=: AT=. Pass control text verbatim to the output.
Spacing:
* @comma: ATcomma. Insert a thin space.
* @/: AT/. Insert a line break.
* @|: AT|_. Insert optional line break in an expression.
* @#: AT#. Force line break with blank line.
* @~: AT~. Cancel a line break (tie adjacent lines together).
* @&: AT&. Join left and right items.
Pseudo (invisible) operators:
* @e: ATe. Invisible expression.
* @;: AT;. Invisible semicolon.
* @colon: ATcolon. Invisible colon.
Miscellaneous:
* @!: AT!. Inhibit expansion for next macro.
File: fweb.info, Node: AT0, Next: AT1, Prev: AT commands, Up: AT commands
Debugging commands
==================
Several commands provide localized versions of the `-1' and `-2'
options related to debugging of pretty-printing.
`@0': Turn off debugging
-------------------------
This cancels the effect of a previous `@1' or `@2'. *Note AT1::,
*Note AT2::. The `@0' command should appear in a different section
from the `@1' or `@2' commands.
File: fweb.info, Node: AT1, Next: AT2, Prev: AT0, Up: AT commands
`@1': Display irreducible scraps
---------------------------------
File: fweb.info, Node: AT2, Next: ATAT, Prev: AT1, Up: AT commands
`@2': Display detailed reductions of the scraps
------------------------------------------------
File: fweb.info, Node: ATAT, Next: AT|, Prev: AT2, Up: AT commands
Literal control characters
==========================
`@@': The character `@'.
-------------------------
`@@' inserts the single character `@'.
Don't forget to double the `@' even inside strings. For example,
puts("'@@' is represented by `@@@@'");
File: fweb.info, Node: AT|, Next: ATspace, Prev: ATAT, Up: AT commands
`@|': Literal vertical bar, or optional line break.
----------------------------------------------------
In TeX mode, `@|' inserts a vertical bar. This is useful inside
LaTeX verbatim environments. (A simple bar would signal a shift into
code mode, which is probably not what you want.)
In code mode, `@|' inserts an optional line break in an expression.
File: fweb.info, Node: ATspace, Next: AT*, Prev: AT|, Up: AT commands
Beginning of section
====================
`@ ': Begin minor section.
---------------------------
`@ ' begins a new minor (unstarred) section. For example,
@ This is an example of a minor section. (No entry is made in the table
of contents.)
@a
main()
{}
File: fweb.info, Node: AT*, Next: AT<, Prev: ATspace, Up: AT commands
`@*', `@*n': Begin major section.
----------------------------------
`@*' begins a new major (starred) section (of level 0). The command
must be followed by the name of the section (entry in the table of
contents), followed by a period.
If `@*' is followed by a digit n, it begins a new major section of
level n. For example,
@* MAIN PROGRAM. This begins a major section (of level 0).
@a
main()
{}
@*1 Input routines. Now follow some subroutines.
@a
get_input()
{}
File: fweb.info, Node: AT<, Next: AT>, Prev: AT*, Up: AT commands
Beginning of code part
======================
The code part is begun by the appearance of either `@a' or `@<
Module name @>='.
`@<': Begin module name.
-------------------------
`@<' begins a module name, which has the form `@< TeX text @>'.
Module names inside WEB macro definitions begin with `@#', not `@<'.
File: fweb.info, Node: AT>, Next: ATA_, Prev: AT<, Up: AT commands
`@>': End module name.
-----------------------
`@>' ends a module name, of the form `@< TeX text @>'.
File: fweb.info, Node: ATA_, Next: ATa, Prev: AT>, Up: AT commands
`@A': Begin code part of unnamed section.
------------------------------------------
`@A' begins the code part of an unnamed section. For example,
@ In an unnamed section, the code part begins with `@a'.
@a
main()
{}
File: fweb.info, Node: ATa, Next: ATb, Prev: ATA_, Up: AT commands
`@a': Begin code part of unnamed section, and mark.
----------------------------------------------------
`@a' begins the code part of an unnamed section (just as does `@A'),
and in addition marks the next unreserved identifier it finds as
defined in this section. Precisely,
`@a' == `@A@['
File: fweb.info, Node: ATb, Next: ATc, Prev: ATa, Up: AT commands
Control codes b-z
=================
`@b': Insert a breakpoint command.
-----------------------------------
(To be finished. Useful only for very intimate debugging of WEB
codes.)
File: fweb.info, Node: ATc, Next: ATcpp, Prev: ATb, Up: AT commands
`@c': Set language to C.
-------------------------
*Note Languages::, *Note C::.
File: fweb.info, Node: ATcpp, Next: ATD_, Prev: ATc, Up: AT commands
`@c++': Set language to C++.
-----------------------------
*Note Languages::, *Note Cpp::.
File: fweb.info, Node: ATD_, Next: ATd, Prev: ATcpp, Up: AT commands
`@D': Define outer macro.
--------------------------
*This command begins the definition part.*
`@D' defines an outer macro. For more discussion, *Note Outer
macros::. For example,
@D A 1
File: fweb.info, Node: ATd, Next: ATf, Prev: ATD_, Up: AT commands
`@d': Define outer macro, and mark.
------------------------------------
*This command begins the definition part.*
`@d' defines an outer macro (just as `@D' does), and also marks the
next identifiers as defined here. It is equivalent to
`@d' == `@D@['
File: fweb.info, Node: ATf, Next: ATi, Prev: ATd, Up: AT commands
`@f': Format identifier or module name.
----------------------------------------
*This command begins the definition part.*
The construction
@f identifier old_identifier
makes FWEAVE treat identifier like old_identifier. For example,
@f mytype int
says to treat the variable `mytype' just as `int' is treated (e.g., as
a reserved word in C or C++).
The old_identifier may be one of the following special names, which
insert extra spaces according to the positions of the underscores and
behave as the part of speech indicated by the base names. These are
useful for dealing with macro constructions.
$_BINOP_
$_COMMA_
$_EXPR
$_EXPR_
$EXPR_
$UNOP_
When the current language is TeX, the format command can be used to
change a category code according to the format
@f `TeXchar new_cat_code
File: fweb.info, Node: ATi, Next: ATI_, Prev: ATf, Up: AT commands
`@i': Include file (unconditional).
------------------------------------
If one says
@i test.hweb
the file `test.hweb' is inserted at the present point of the web file.
By default, the current directory is searched. Files can be included
from other directories by means of the `FWEB_INCLUDES' environment
variable and/or the `-I' command-line option. *Note Environment
variables::, *Note -I_::.
File: fweb.info, Node: ATI_, Next: ATL_, Prev: ATi, Up: AT commands
`@I': Include file (conditional).
----------------------------------
This commands behaves like `@i' if the command-line option `-i' is
not used. If it is used, then the contents of the included file is not
printed in the woven output. *Note -i::, *Note -i!::.
File: fweb.info, Node: ATL_, Next: ATl, Prev: ATI_, Up: AT commands
`@L': Set language.
--------------------
`@Ll' sets the language to l, where l is one of
`{c,c++,n,n9,r,r9,x,v}'. *Note Languages::.
File: fweb.info, Node: ATl, Next: ATM_, Prev: ATL_, Up: AT commands
`@l': Specify limbo text.
--------------------------
(This command begins the definition part.)
Limbo text is material that FWEAVE should output before the start of
the first section. For example,
@l "\\def\\A{abc}"
Note that `\\' stands for a backslash. In general, characters must be
escaped just as in C (so that one can include things like newlines in
the definitions).
Limbo text may also be typed directly into the limbo section; in that
case, no escapes are necessary since one is typing ordinary TeX text.
Sometime, however, the `@l' command is useful for pedagogical purposes,
as the limbo material can then be defined near the point where the
logical discussion is made.
File: fweb.info, Node: ATM_, Next: ATm, Prev: ATl, Up: AT commands
`@M': Define WEB macro.
------------------------
*This command begins the definition part.*
For a detailed discussion of WEB macros, see *Note Macros::.
File: fweb.info, Node: ATm, Next: ATN_, Prev: ATM_, Up: AT commands
`@m': Define WEB macro, and mark.
----------------------------------
*This command begins the definition part.*
For a detailed discussion of WEB macros, see *Note Macros::.
File: fweb.info, Node: ATN_, Next: ATn, Prev: ATm, Up: AT commands
`@N': Turn on N mode
---------------------
*This command must appear before the code part.*
The N mode invokes language-independent behavior within the scope of
a particular language. The scoping rules are the same as for language
changes; i.e., using `@N' within a given section produces
language-independent behavior for that section and for any modules first
referenced in that section.
Fundamentally, "language-independent" behavior essentially means a
literal transcription of the input to the output. For example, it
inhibits blank compression by FTANGLE and tells FWEAVE to turn off
"pretty-printing" (instead, the output is printed in typewriter type
within a `\begin{verbatim}...\end{verbatim}' environment.
There are some subtleties with this mode (not to mention the
likelihood of bugs):
1. WEB macros and built-in functions will normally be expanded even
in the N mode. To inhibit expansion of a particular identifier,
place `@!' before the identifier. For example,
@
@m A 1
@N
@a
@!A = A;
expands to `A = 1'.
2. Blank lines are significant. The N mode is ended by the
appearance of the `@*' or `@ ' denoting the start of the next
section. If that were preceded by one or more blank lines, those
would show up in both the tangled and woven output. They might or
might not be significant in the tangled output, but they almost
certainly will look ugly in the woven output. To avoid this, use
the command `@%%', which deletes the remainder of the current line
and all immediately following empty lines. For example,
@
@N
@a
x;@%%
@ Next section.
3. If the N mode is invoked from a compiler-like language such as
Fortran, cross-referencing of variables is done as usual.
However, if the language is VERBATIM (which turns on the N mode
automatically), no cross-referencing is done. (Identifiers are
still recognized according to FWEB's rules. Those rules as
currently implemented may be essentially meaningless for some
languages; in the future, provision may be made for generalizing
these rules by the user.) To force an identifier to be placed
into the index, precede it by `@+'.
File: fweb.info, Node: ATn, Next: ATn9, Prev: ATN_, Up: AT commands
`@n': Set language to Fortran-77.
----------------------------------
*Note Languages::.
File: fweb.info, Node: ATn9, Next: ATO_, Prev: ATn, Up: AT commands
`@n9': Set language to Fortran-90.
-----------------------------------
*Note Languages::.
File: fweb.info, Node: ATO_, Next: ATo, Prev: ATn9, Up: AT commands
`@O': Open output file (global scope).
---------------------------------------
A statement of the form
@O newfile.c
changes the name of the FTANGLE's output file. This change remains in
effect for the duration of the file, or until another `@O' is
encountered. (If that occurs, the previously open file is closed.)
This command is expanded during output, so it must appear in the
code part.
File: fweb.info, Node: ATo, Next: ATr, Prev: ATO_, Up: AT commands
`@o': Open output file (local scope).
--------------------------------------
This behaves like `@O', except the new file name is in effect only
for the current section.
File: fweb.info, Node: ATr, Next: ATr9, Prev: ATo, Up: AT commands
`@r': Set language to Ratfor-77.
---------------------------------
*Note Languages::.
File: fweb.info, Node: ATr9, Next: ATu, Prev: ATr, Up: AT commands
`@r9': Set language to Ratfor-90.
----------------------------------
*Note Languages::.
File: fweb.info, Node: ATu, Next: ATv, Prev: ATr9, Up: AT commands
`@u': Undefine outer macro.
----------------------------
*This command begins the definition part.*
`@u' is the inverse of `@d'. For example, in C it expands to
`#undef'.
File: fweb.info, Node: ATv, Next: ATW_, Prev: ATu, Up: AT commands
`@v': Overload operator.
-------------------------
*This command begins the definition part.*
For a detailed discussion of overloading operators, see *Note
Overloading::.
File: fweb.info, Node: ATW_, Next: ATx, Prev: ATv, Up: AT commands
`@W': Overload identifier.
---------------------------
*This command begins the definition part.*
For a detailed discussion of overloading identifiers, see *Note
Overloading::.
File: fweb.info, Node: ATx, Next: ATy, Prev: ATW_, Up: AT commands
`@x': Terminate ignorable material, or begin material to be changed
--------------------------------------------------------------------
Please see the discussion of the `@z' command. *Note ATz::.
File: fweb.info, Node: ATy, Next: ATz, Prev: ATx, Up: AT commands
`@y': Begin change material
----------------------------
The `@y' command is permitted only in change files. *Note Change
files::.
File: fweb.info, Node: ATz, Next: ATquote, Prev: ATy, Up: AT commands
`@z': Begin ignorable material, or terminate change
----------------------------------------------------
FWEB files may begin with the construction
@z
.
.
@x
where the `@z' and `@x' must begin in column 1. Material between the
`@z' and `@x' is "pure commentary" and is ignored by both processors.
`@z' is also used in change files to end a change. *Note Change
files::.
File: fweb.info, Node: ATquote, Next: AT", Prev: ATz, Up: AT commands
Conversion to ASCII
===================
Several commands are useful for generating machine-independent code.
For example, FWEB works internally with the ASCII character set, so
uses these commands heavily to convert from the possibly non-ASCII
native character set of the machine on which FWEB is running.
`@'': Convert character to ASCII.
----------------------------------
The construction `@'c'' converts `c' to its ASCII value. In C and
C++, it is converted to octal; for example, `@'A'' is output as `0101'.
In Fortran and Ratfor, it is converted to decimal; the previous example
would be output as `65'.
If the native character set of your machine is ASCII, the conversion
will not be done unless the `-A' command-line option is used. *Note
-A_::.
File: fweb.info, Node: AT", Next: AT[, Prev: ATquote, Up: AT commands
`@"': Convert string to ASCII.
-------------------------------
The construction `@"abc"' converts the enclosed string to its ASCII
representation. For example, in C and C++ `@"abc"' will be output as
`"\141\142\143"'.
In Fortran and Ratfor, no such simple mechanism exists in the
language, so a function call is issued. For example, the previous
example would be output as `ASCIIstr('abc')'. The user is responsible
for defining the function `ASCIIstr'. The name of this function can be
changed by the style-file entry `ASCII_fcn'. *Note ASCII_fcn::.
If the native character set of your machine is ASCII, the conversion
will not be done unless the `-A' command-line option is used. *Note
-A_::.
File: fweb.info, Node: AT[, Next: AT/*, Prev: AT", Up: AT commands
Forward referencing
===================
`@[': Mark as defined.
-----------------------
This command marks the next (non-reserved) identifier that appears
after the `@[' as being defined in the current section. It is usually
issued automatically; for example, `@a' is equivalent to `@A@['.
File: fweb.info, Node: AT/*, Next: AT//, Prev: AT[, Up: AT commands
Comments
========
`@/*': Begin long verbatim comment.
------------------------------------
The following comment is copied to the tangled output. If you desire
all comments to be so copied, use `-v'. *Note -v::.
File: fweb.info, Node: AT//, Next: AT%, Prev: AT/*, Up: AT commands
`@//': Begin short verbatim comment.
-------------------------------------
See the discussion of `@/*', above.
File: fweb.info, Node: AT%, Next: AT?, Prev: AT//, Up: AT commands
`@%': Ignorable comment.
-------------------------
If any line in a web source code contains the command `@%', all
remaining material on that line (to and including the newline character)
is ignored by the input driver and never processed at all.
A stronger form of this command is `@%%'. This deletes the current
line as well any empty lines that immediately follow. This command is
particularly useful when the N mode is in effect. *Note ATN_::.
File: fweb.info, Node: AT?, Next: ATlp, Prev: AT%, Up: AT commands
`@?': Begin compiler directive.
--------------------------------
The remainder of the line is processed as a compiler directive.
Optional material may be inserted automatically at the beginning of the
tangled output line by means of the style-file option `cdir_start'.
*Note Miscellaneous params::.
File: fweb.info, Node: ATlp, Next: AT), Prev: AT?, Up: AT commands
`@(': Begin meta-comment.
--------------------------
Material between `@(' and `@)' is treated in the N mode. For
example,
@(
Comment 1
Comment 2
@)
Style-file parameters allow optional material to be insert at the
beginning and end of the meta-comment, and at the beginning of each line
of output. For more information, see the style-file parameters
beginning with `meta' (*note Miscellaneous params::.).
File: fweb.info, Node: AT), Next: ATlb, Prev: ATlp, Up: AT commands
`@)': End meta-comment.
------------------------
See the discussion of `@(', *Note ATlp::.
File: fweb.info, Node: ATlb, Next: AT_, Prev: AT), Up: AT commands
Special brace
=============
`@{': Suppress insertion of breakpoint command.
------------------------------------------------
This is for detailed debugging of FWEB codes. It inserts a left
brace and suppresses the insertion of a breakpoint command. *Note
ATb::.
File: fweb.info, Node: AT_, Next: AT-, Prev: ATlb, Up: AT commands
Index entries
=============
`@_': Force index entry to be underlined.
------------------------------------------
This command applies to the next identifier that appears after the
`@_'. The index entry for that identifier will be underlined.
This command is usually issued automatically. For example, the index
entries for the variables `i' and `j' in the C statement `int i,j;'
will be underlined.
File: fweb.info, Node: AT-, Next: ATplus, Prev: AT_, Up: AT commands
`@-': Delete index entry.
--------------------------
This command applies to the next identifier that appears after the
`@-'; it prevents the index entry associated with that identifier from
being underlined. This might be useful when the N mode is in effect.
File: fweb.info, Node: ATplus, Next: AT^, Prev: AT-, Up: AT commands
`@+': Force index entry.
-------------------------
This command applies to the next identifier that appears after the
`@+'; it forces an index entry for that identifier. It is particularly
useful when the language is VERBATIM, since cross-referencing is turned
off in that case.
File: fweb.info, Node: AT^, Next: ATdot, Prev: ATplus, Up: AT commands
`@^': Make index entry (Roman type).
-------------------------------------
To insert one's own index entry in Roman type, say `@^My entry@>'.
File: fweb.info, Node: ATdot, Next: AT9, Prev: AT^, Up: AT commands
`@.': Make index entry (typewriter type).
------------------------------------------
To insert one's own index entry in typewriter type, say `@^My
entry@>'.
File: fweb.info, Node: AT9, Next: ATt, Prev: ATdot, Up: AT commands
`@9': Make index entry (\9 format).
------------------------------------
The construction `@9text@>' is used to create an index entry in a
format defined by the user. It is associated with the macro `\9', which
would be called during TeX's processing of the index as `\9{text}'.
The user must define `\9' according to the format
\def\9#1{...}
File: fweb.info, Node: ATt, Next: AT=, Prev: AT9, Up: AT commands
Control text
============
`@t': Put control text into a TeX \hbox.
-----------------------------------------
Control text is material terminated by `@>'; it must be all on one
line and must not contain any `@'s. When FWEAVE sees the command
`@tcontroltext@>', it packages the control text into an `\hbox' and
ships it to the output. This command is ignored by FTANGLE.
File: fweb.info, Node: AT=, Next: ATcomma, Prev: ATt, Up: AT commands
`@=': Pass control text verbatim to the output.
------------------------------------------------
For FTANGLE, the command `@=controltext@>' sends the control text to
the output exactly as input. (`Control text' is defined in the
discussion of the `@t' command, *Note ATt::.) FWEAVE highlights the
control text by drawing a box around it.
File: fweb.info, Node: ATcomma, Next: AT/, Prev: AT=, Up: AT commands
Spacing
=======
The spacing commands are used to refine FWEAVE's pretty-printed
output. Generally it's not necessary to bother with these until you're
putting the final touches on a code.
`@,': Insert a thin space.
---------------------------
Extra spacings are sometimes necessary when working with unusual
macro constructions. (Need an example here.)
File: fweb.info, Node: AT/, Next: AT|_, Prev: ATcomma, Up: AT commands
`@/': Force a line break.
--------------------------
For example,
int@/
i,@/
j,@/
k;
File: fweb.info, Node: AT|_, Next: AT#, Prev: AT/, Up: AT commands
`@|': Literal vertical bar, or optional line break.
----------------------------------------------------
In TeX mode, `@|' inserts a vertical bar. Here's a LaTeX example:
\begin{verbatim}
The constructions @|x@| and |x| are very different.
\end{verbatim}
You might wish to try this out to see what FWEAVE produces.
In code mode, `@|' inserts an optional line break in an expression.
File: fweb.info, Node: AT#, Next: AT~, Prev: AT|_, Up: AT commands
`@#': Blank line.
------------------
`@#' forces a line break with some extra vertical white space. Note
that blank lines in the source are significant, so this command should
seldom be necessary.
if `@#' is immediately followed by a letter, it is assumed that a
preprocessor command is beginning. *Note Preprocessing::.